home *** CD-ROM | disk | FTP | other *** search
/ CU Amiga Super CD-ROM 17 / CU Amiga Magazine's Super CD-ROM 17 (1997)(EMAP Images)(GB)[!][issue 1997-12].iso / CUCD / Programming / DiceSource / src / dicecache / dicecache.doc < prev    next >
Text File  |  1994-07-29  |  4KB  |  117 lines
  1.  
  2.                    DICECACHE.DOC
  3.  
  4.     DICECACHE.LIBRARY implements whole file caching for any DICE executable
  5.     that goes through the stdio/fd interface.  DICE EXECUTABLES DO NOT
  6.     REQUIRE DICECACHE.LIBRARY TO RUN BUT CAN RUN, POTENTIALLY, MUCH FASTER
  7.     IF DICECACHE.LIBRARY EXISTS.
  8.  
  9.     DICECACHE SHOULD ONLY BE USED WITH MACHINES CONTAINING 1.5MB OF RAM OR
  10.     GREATER.  A 1MB machine does not have enough memory to utilize
  11.     DICECACHE.
  12.  
  13.     Currently, DICECACHE.LIBRARY will be used only with files openned for
  14.     read-only operations... that is, modes "r" or "rb".  stdio reading
  15.     functions such as getc(), fgets(), and fread() will be virtually
  16.     instantanious.
  17.  
  18.     DICECACHE.LIBRARY caches files by extension, installed with the
  19.     'dicecache' command as follows:
  20.  
  21.     1> dicecache on        ; turn on caching
  22.     1> dicecache ADD .c ADD .h ADD .lib ; add suffixes to the cachable list
  23.     1> dicecache off        ; turn off caching
  24.     1> dicecache ?        ; print available keywords, additional commands
  25.  
  26.     DICECACHE caches whole files at a time, assuming the fit in the cache.
  27.     If the cache fills up, space is made by freeing the data for whole
  28.     files at a time on a random basis (weighted according to the size of
  29.     the file so small files generally stick around).  This ensures that
  30.     even if your cache is not large enough to fit your design cycle that a
  31.     speed improvement will still occur.
  32.  
  33.     * Warning:    Dicecache does NOT currently free entries under low memory
  34.     conditions.  Do not specify a cache size (using dicecache MAXSIZE <n>)
  35.     greater then your machine can accomodate.
  36.  
  37.     DICECACHE commands:
  38.  
  39.         ADD <suffix>
  40.  
  41.             Add a suffix to the list of cachable file suffixes.
  42.  
  43.         REM <suffix>
  44.  
  45.             remove a suffix from the list of cachable file suffixes.
  46.  
  47.         ON
  48.  
  49.             enable caching
  50.  
  51.         OFF
  52.  
  53.             disable caching
  54.  
  55.         FLUSH
  56.  
  57.             flush cached files.  Note that files in active operation
  58.             will not be flushed.
  59.  
  60.         MAXFILE <nfiles>
  61.  
  62.         set maximum number of files dicecache will keep track of.
  63.         When the limit is reached, dicecache will begin to flush
  64.         random files.
  65.  
  66.         MAXSIZE <size>
  67.  
  68.             only files less then the specified size will be cached.
  69.             files larger then the specified size will not be cached.
  70.  
  71.     STATUS LINE:
  72.  
  73.         "Cached AA/BB/CC filemax=DD hit=EE/FF (NN %) suffixes=<suffixes>"
  74.  
  75.         AA        - number of cached bytes currently in use
  76.         BB        - total number of bytes currently cached
  77.         CC        - maximum number of bytes that can be cached
  78.         filemax=DD    - maximum number of files that can be cached
  79.         hit=EE/FF    - cache hit on EE out of FF files
  80.         NN %        - cache hit percentage
  81.         <suffixes>    - list of suffixes being cached.
  82.  
  83.  
  84.                   LIBRARY CALLS
  85.  
  86.     (DICE's stdio/fd routines automatically utilize DICECACHE if it is
  87.     enabled.  If you wish to use it manually you may do so, but you MUST
  88.     check DiceCacheBase before doing so.  DICE will automatically open
  89.     dicecache.library and setup DiceCacheBase if it exists, otherwise
  90.     DiceCacheBase will be left NULL.  Do NOT declare DiceCacheBase as doing
  91.     so will *disable* DICE's autoinit for it.  Instead, simply extern it.
  92.  
  93.  
  94.     CacheDesc = DiceCacheOpen(fileName, modes, &fileSize)
  95.  
  96.     Returns NULL if the file could not be found or is uncacheable.
  97.     fileName and modes are as in fopen().  If successfull, fileSize is
  98.     set to the size of the file.
  99.  
  100.     This call Examine()'s and compares timestamps, re-caching the file
  101.     if it has been modified.  In order for this operation to be fast
  102.     you should ensure that you have enough buffers (with the CLI
  103.     ADDBUFFERS command) to cache file headers for any conceivable
  104.     usage.
  105.  
  106.     (void) DiceCacheClose(CacheDesc)
  107.  
  108.     Close a previously openned file cache
  109.  
  110.     ptr = DiceCacheSeek(CacheDesc, pos, &size)
  111.  
  112.     Seek within a cached file.  This call returns a pointer to an
  113.     internal buffer along with the maximum number of contiguous bytes
  114.     in that buffer.
  115.  
  116.  
  117.